Zum Hauptinhalt springen

Wo lebt das V-Modell bei Softwareentwicklung?

Wenn dein Produkt Software enthaelt, ist das V-Modell die Referenz dafuer, wie Anforderungen bis zur Implementierung hinunterfliessen und ueber Verifikation und Validierung wieder hinauf. Die Frage, die sich die meisten Teams stellen, lautet: Welche Teile dieses Modells gehoeren nach CertHub, und welche bleiben in der Engineering-Umgebung?

Die kurze Antwort: Die V-Modell-Records leben in CertHub. Implementierung und Test-Ausfuehrung leben ausserhalb. Das ist keine CertHub-Konvention. So trennen Design Controls im Medizinproduktbereich bereits eine Traceability-Matrix kontrollierter Artefakte vom letzten Schritt in den Quellcode.

Zwei Aufgaben, nicht ein Annotationsschema​

Einsteiger fragen oft: Wenn ich Systemanforderungen synchronisieren muss, warum steht dann nicht SYSREQ an jeder Funktion? Weil das zwei verschiedene Aufgaben sind.

Aufgabe 1 — QMS / technische Dokumentation. ISO 13485 verlangt, dass du Methoden dokumentierst, um die Rueckverfolgbarkeit der Design- und Entwicklungs-Outputs zu den Design- und Entwicklungs-Inputs sicherzustellen (ISO 13485:2016 Abschnitt 7.3.2(e); derselbe Text steht in den USA jetzt in der QMSR ueber 21 CFR 820). Diese Methode ist eine bidirektionale Matrix von Records: Benutzeranforderungen, Design-Inputs, Design-Outputs, Verifikation, Validierung. Auditoren gehen diese Matrix durch. Sie greppen nicht dein Repository nach Anforderungs-IDs.

Aufgabe 2 — dieser Git-Stand. Die FDA-General Principles of Software Validation (GPSV, 2002) §5.2.4 verlangen eine Source-Code-Traceability-Analyse: Module und Funktionen lassen sich auf ein Element der Software-Design-Spezifikation zurueckfuehren, und Tests auf dieselbe Spezifikation. Die Design-Spezifikation ist ein Design Output, keine Systemanforderung.

Zusammen:

CertHub (Aufgabe 1)                     Engineering (Aufgabe 2)
UREQ → SYSREQ → DOUT ───────────────►  Quellcode mit DOUT markiert
              ↘ VERIF ──────────────►  Test mit VERIF markiert
UREQ → VALID                           (manuell / Zweckbestimmung — keine Unit-Tests)

Du synchronisierst die linke Seite, damit die Matrix in deinen Tools existiert. Du markierst nur die rechte Seite, weil GPSV genau diesen Schritt fuer den Quellcode benennt. SYSREQ an Funktionen zu setzen wuerde die Design-Output-Schicht ueberspringen, gegen die Verifikation definiert ist (ISO 13485 7.3.6: Verifikation soll bestaetigen, dass der Design Output die Design-Input-Anforderungen erfuellt; 21 CFR 820.30(f)).

IEC 62304 sagt dasselbe in der Planungssprache: Der Software-Entwicklungsplan soll TRACEABILITY zwischen SYSTEM-Anforderungen, Software-Anforderungen, SOFTWARE-SYSTEM-Test und in Software umgesetzten RISK-CONTROL-Massnahmen behandeln (IEC 62304:2006+A1:2015 5.1.1(c)). Diese Traces leben zwischen kontrollierten Records. Quellcode-Kommentare sind eine Engineering-Methode fuer den letzten Schritt, kein Ersatz fuer die Matrix.

Die empfohlene Aufteilung​

Records — in CertHub pflegen​

Halte Folgendes als kontrollierte, pruefbare Records, einschliesslich der Traces dazwischen:

  • Benutzeranforderungen (User Needs)
  • System- / Software-Anforderungen (Design Inputs)
  • Komponenten- und Unit-Anforderungen, falls du diese Schichten nutzt
  • Design Outputs (die Software-Design-Spezifikation und zugehoerige Spezifikationen)
  • Verifikation (die kontrollierte Definition der Aktivitaet — und, wenn du sie ablegst, das Ergebnis)
  • Validierung (die kontrollierte Definition der Aktivitaet zur Zweckbestimmung)
  • die Tracer-Kanten, die die Matrix bidirektional machen

Das ist die Sicht auf die technische Dokumentation, die QM und RA brauchen, um zu pruefen, zu verteidigen und freizugeben. Genau dafuer ist CertHub gebaut.

Design Output gehoert hierher als Record. ISO 13485 7.3.4 verlangt, dass Outputs in einer Form dokumentiert sind, die sich gegen Inputs verifizieren laesst, Annahmegrenzen enthalten oder referenzieren und vor der Freigabe genehmigt werden. Die Quelldatei, die einen Output umsetzt, ersetzt diesen Record nicht.

Ausfuehrung — deine Engineering-Umgebung​

Alles, was ein Build, ein Lauf oder ein generierter Report ist, bleibt dort, wo das Engineering-Team arbeitet:

  • Code und Implementierung
  • Unit- und Integrationstest-Ausfuehrung
  • Dashboards und generierte Evidenzpakete pro Commit
  • Build-Artefakte und CI-Pipelines

Wie du den letzten Schritt (Aufgabe 2) umsetzt, ist deine Engineering-Entscheidung: Kommentare im CodeLinks-Stil, Doorstop, Doxygen, ein kleines Skript gegen die API. Das Muster schreibt keine bestimmte Toolchain vor. Siehe Working example.

CertHub muss nicht zu deiner IDE oder deinem CI-System werden.

Warum du Schichten synchronisierst, die du nie im Code markierst​

Exportiere das gesamte V-Modell, das du pflegst, nicht nur die IDs, die in Kommentaren stehen.

  • Vollstaendigkeit ist der Sinn von 7.3.2(e). Ein Input ohne Output ist eine fallen gelassene Anforderung. Ein Output ohne Input ist Scope Creep. Wenn der Engineering-Export unverbundene Zeilen weglaesst, versteckst du den Befund, den die Matrix zeigen soll.
  • Fremdprodukt- oder Alttext ist ein Problem des Systems of Record. Bereinige ihn in CertHub. Streiche kein Knowledge Topic aus dem Sync, nur weil einige Zeilen keinen Code haben.
  • Validierung ist eine andere Frage als Verifikation. 21 CFR 820.30(g) und ISO 13485 7.3.7 fragen, ob das Produkt Benutzeranforderungen und Zweckbestimmung erfuellt, typischerweise unter realer oder simulierter Nutzung. Das ist nicht „hat der Unit-Test bestanden?“. Synchronisiere Validierungsprotokolle; tu nicht so, als wuerde pytest sie schliessen.
  • Es darf Zeilen ohne Software geben. Verfahrens-Design-Outputs, Kennzeichnungsspezifikationen oder Hardware-Outputs bleiben im Katalog. Sie haben einfach keinen Source-Marker. Das ist korrekt, kein unvollstaendiges Tagging.

AAMI TIR45:2023 (von der FDA anerkannt, Recognition Number 13-143) ist die uebliche Referenz, das in einem Agile-Team zu tun: Traces sind Lifecycle-Outputs, die laufend gepflegt werden, kein Kommentar-Schema erst zum Release.

Was diese Aufteilung nicht behauptet: IEC 62304 5.1.1(c) nennt auch Risk-Control-Massnahmen. Die bleiben in der Risikodatei (ISO 14971) in CertHub, sofern du sie nicht explizit exportierst. Quellcode-Kommentare sind eine Methode fuer den letzten GPSV-Schritt; die Norm verlangt die Traces, keine bestimmte Marker-Syntax.

Zwei Richtungen, nicht eine​

Diese Aufteilung erzeugt zwei Datenbewegungen, und die meisten Teams brauchen beide.

1. Export: V-Modell-Records gehen hinaus​

Deine Engineering-Tools brauchen die kontrollierten Records und die Traces. Exportiere sie ueber die API aus CertHub, damit Git, Jira, Sphinx, Azure DevOps oder ein interner Service sie nutzen koennen.

Das ist eine Leseoperation. CertHub bleibt das System of Record. Deine Tools bekommen eine synchronisierte Kopie der Matrix — einschliesslich Zeilen, die du nie im Quellcode markieren wirst.

2. Zurueckschreiben: ausgewaehlte Nachweise kommen zurueck​

Wenn dein Engineering-Prozess ein Ergebnis produziert, das fuer die technische Dokumentation relevant ist, schreibe einen kurzen Nachweis-Record zurueck nach CertHub.

Das ist typischerweise ein Record auf Release-Ebene, keine Kopie jedes Testlaufs. Ein praktisches Minimum ist:

  • eine Versionsnummer
  • ein Commit- oder Build-Bezeichner
  • ein Zeitstempel
  • eine URL, die auf den vollstaendigen Nachweis verweist (zum Beispiel ein CI-Lauf oder ein Report in deinem Artefakt-Store)
  • eine kurze Zusammenfassung des Gate-Ergebnisses

Der komplette Build-Baum, die vollstaendige JUnit-Ausgabe, die generierten HTML-Dashboards — die bleiben in deinem CI- oder Artefakt-Store. CertHub erhaelt den kontrollierten Verweis und die Zusammenfassung, die ihr tatsaechlich prueft.

Du bestimmst die Tiefe​

Wie viel du zurueckschreibst, ist eine Entscheidung deines Teams. Manche Organisationen schreiben einen einzigen Release-Record pro Version. Andere schreiben granularere Records pro Verifikationsaktivitaet.

Die Empfehlung: Beginne mit dem Minimum, das QM und RA das gibt, was sie brauchen. Du kannst spaeter immer mehr Tiefe hinzufuegen. Du solltest nicht versuchen, die gesamte Engineering-Umgebung in CertHub zu replizieren.

Auf der Export-Seite ist die uebliche Tiefe das V-Modell, das ihr tatsaechlich pflegt (oft sieben Content-Topics plus Traces). Du musst nicht jede Schicht in Software umsetzen. Du musst sie sehen, wenn sie im SoR steht.

Ein Beispiel, nicht die Methode​

Cadence ist CertHubs oeffentliches Engineering-Beispiel fuer dieses Muster. Es nutzt die CertHub-API; useblocks (Sphinx-Needs / CodeLinks / Test-Reports) ist der optionale Last-Hop-Toolchain in diesem Repo, keine CertHub-Vorgabe.

Cadence synchronisiert sieben Requirements-Engineering-Knowledge-Topics aus CertHub in eine Git-Codebasis. Quellcode-Kommentare nutzen Design-Output-IDs; Tests nutzen Verifikations-IDs. Systemanforderungen schliessen das Engineering-Gate ueber Tracer-Links, nicht ueber zusaetzliche Kommentare. Es erstellt bei jedem Commit ein vollstaendiges Evidenzpaket und schreibt bei vollstaendigen Versions-Tags einen Release-Nachweis-Record zurueck nach CertHub.

Nutze es als Referenzimplementierung. Ersetze den unteren Teil des V durch deinen eigenen Stack — das Muster bleibt gleich. Siehe Working example fuer das annotierte V und die zwei Downstream-Anwendungen (Traceability bis zum Code sowie Tests plus gezielter Write-back), oder schau dir den Walkthrough an.

Beispiel lokal ausprobieren
git clone https://github.com/CertHubCode/certhub-useblocks-example.git
cd certhub-useblocks-example
make install
make show              # Tests + Gate + Dashboard oeffnen — erwartet VERIFIED, 4/4 SYSREQ PASS (kein API-Key)

API-Key erst fuer Sync oder Release-Record-Write-back (cp .env.example .env, dann make sync). Die README im Repository beschreibt den gefuehrten Pfad, die RED/GREEN-Demo (make break / make fix) und das CI-Setup. docs/traceability-map.md in diesem Repo ist das ausgearbeitete Beispiel, was im Code markiert wird und warum.

Was du nicht tun solltest​

  • Versuche nicht, deinen gesamten Engineering-Workflow in CertHub abzubilden.
  • Belasse Anforderungen, Design Outputs und Verifikation nicht nur in deinem Entwicklungstool, ohne eine kontrollierte Kopie in der technischen Dokumentation.
  • Setze keine Systemanforderungs-IDs auf den Quellcode als Ersatz fuer den Design-Output-Record. Verifikation bestaetigt, dass der Output den Input erfuellt.
  • Streiche unverbundene Zeilen nicht aus dem Export, damit das Paket aufgeraeumter wirkt. Vollstaendigkeit ist der Befund.
  • Kippe nicht den gesamten CI-Artefakt-Baum nach CertHub. Speichere ihn dort, wo er hingehoert, und schreibe einen Verweis zurueck.
  • Baue keinen Custom-Sync, ohne vorher zu verstehen, welche IDs CertHub fuer API-Aufrufe und welche fuer Dashboard-URLs verwendet. Sie sind nicht austauschbar.

Empfehlung​

Fuer Software als Medizinprodukt: Pflege die V-Modell-Records und ihre Traces in CertHub. Lass Engineering den letzten Schritt in Quellcode und Testausfuehrung verantworten. Verbinde beides ueber die API: Exportiere die Matrix, die deine Tools brauchen, schreibe zurueck, was die technische Dokumentation braucht.

Faustregel: Synchronisiere das V-Modell; markiere im Code nur, was Software tatsaechlich umsetzt oder verifiziert. Unverbundene Zeilen sind in Ordnung. Fremdprodukt-Zeilen sind ein Problem des Systems of Record, kein Grund, weniger zu synchronisieren.

Wenn du bereit bist​